Skip to content

Doc migration#491

Open
Becheler wants to merge 46 commits into
boostorg:developfrom
Becheler:doc-migration
Open

Doc migration#491
Becheler wants to merge 46 commits into
boostorg:developfrom
Becheler:doc-migration

Conversation

@Becheler
Copy link
Copy Markdown
Collaborator

@Becheler Becheler commented May 19, 2026

Migrate Boost.Graph documentation to Antora

NOTE: There is no way to split this PR properly, as all .html files need to be replaced all at once.
NOTE: The ~40000 lines of change in doc source code don't need direct review. Instead please review the preview currently hosted on the fork's Github Pages: https://becheler.github.io/graph/graph/index.html

This PR switches Boost.Graph from the pre-baked BoostBook/Quickbook HTML at doc/*.html to an Antora source tree under doc/modules/ROOT/. Once merged, the next Boost release will publish the new site at www.boost.org/doc/libs/<version>/libs/graph/ automatically (release-tools auto-detects doc/build_antora.sh).

Changes

  • New Antora source tree at doc/modules/ROOT/ with 209 .adoc pages and 154 paired .cpp/.txt example sidecars.
  • Wires release-tools' Antora pipeline via doc/build_antora.sh, doc/package.json (antora 3.1.14 + lunr extension), and doc/package-lock.json for reproducible installs.
  • Deletes 180 legacy HTML files at doc/*.html / doc/*.htm, superseded by the Antora pages.
  • Deletes legacy image assets doc/figs/ (106 files) and doc/stoer_wagner_imgs/ (15 files); the new doc carries its own copies under doc/modules/ROOT/assets/images/.
  • Deletes 3 partial reST remnants (read_graphml.rst, read_graphviz.rst, write_graphml.rst), replaced by doc/modules/ROOT/pages/io/{graphml,graphviz}.adoc.
  • Deletes doc/Makefile (LaTeX/pdflatex/dvips rules from 2002, no longer used by any toolchain in the repo).

Verification

  • cd doc && ./build_antora.sh playbook.yml succeeds end-to-end and produces doc/build/site/graph/index.html.

Known follow-ups (not blocking this PR)

  • I had to delete the develop louvain html documentation on this PR to solve conflicts: it will require a new .adoc documentation once this PR ships.
  • CI freshness checks for examples output (git diff --exit-code on .txt after rebuild), may be best to defer until the random-generator examples are RNG-seeded so the diff is deterministic. Also maybe over-engineered.

@Becheler Becheler self-assigned this May 19, 2026
@Becheler Becheler requested a review from jeremy-murphy May 19, 2026 10:08
@Becheler Becheler added the docs label May 19, 2026
@cppalliance-bot
Copy link
Copy Markdown

An automated preview of the documentation is available at https://491.graph.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-19 15:18:38 UTC

@Becheler Becheler marked this pull request as ready for review May 21, 2026 07:41
@Becheler Becheler added priority: medium Important but not blocking. Should be addressed soon, can wait a release or two. priority: high Blocks users or core functionality. Needs attention in the current cycle. and removed priority: medium Important but not blocking. Should be addressed soon, can wait a release or two. labels May 23, 2026
@Becheler
Copy link
Copy Markdown
Collaborator Author

Plan to merge in order: #469#489#491

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs priority: high Blocks users or core functionality. Needs attention in the current cycle.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants